/**
 * ============================================
 * 应用通用路由模块 - app.js
 *
 * 功能说明：
 * - 提供应用通用的API接口，如国家列表等基础数据
 * - 这些接口通常不需要用户登录即可访问
 * - 使用MySQL数据库查询国家信息
 * - 返回标准化的JSON响应格式
 *
 * 路由前缀：/api/app（在app.js中注册时指定）
 * 示例接口：GET /api/app/countries
 *
 * 响应格式：
 * - 成功：{status: 0, msg: '成功消息', data: 数据}
 * - 失败：{status: 1, msg: '错误消息', data: null}
 * ============================================
 */

// 引入Express框架 - 用于创建路由和处理HTTP请求
const express = require('express');
// 引入数据库查询函数 - 从database配置模块导入query函数，用于执行SQL查询
const { query } = require('../config/database');

/**
 * 创建Express路由实例
 * 功能：定义一组相关的API端点
 * 在app.js中通过app.use('/api/app', router)注册此路由
 */
const router = express.Router();

/**
 * ====================
 * 获取国家列表接口
 * ====================
 * 接口：GET /countries
 * 功能：从数据库查询所有国家信息，用于前端下拉选择框等场景
 * 特点：公开接口，无需认证即可访问
 *
 * @param {Object} req - Express请求对象（不需要参数）
 * @param {Object} res - Express响应对象，返回国家列表数据
 * @returns {JSON} 标准化的响应数据
 */
router.get('/countries', async (req, res) => {
  try {
    /**
     * 执行数据库查询
     * SQL语句说明：
     * - SELECT code as value, name as label: 查询国家代码和名称，重命名为value和label
     * - FROM countries: 从countries表查询
     * - ORDER BY name: 按国家名称字母顺序排序
     *
     * 字段映射原因：
     * - value: 国家代码，作为下拉选项的值
     * - label: 国家名称，作为下拉选项的显示文本
     * 这种格式便于前端组件（如Select、Dropdown）直接使用
     */
    const countries = await query(
      'SELECT code as value, name as label FROM countries ORDER BY name'
    );

    /**
     * 返回成功响应
     * 响应格式说明：
     * - status: 0 表示成功
     * - msg: 成功提示消息
     * - data: 查询到的国家列表数据
     */
    res.json({
      status: 0,
      msg: '获取国家列表成功',
      data: countries
    });

  } catch (error) {
    /**
     * 错误处理
     * 捕获数据库查询或其他操作中可能出现的错误
     */
    console.error('获取国家列表错误:', error);
    
    /**
     * 返回错误响应
     * 响应格式说明：
     * - status: 1 表示错误
     * - msg: 错误提示消息
     * - data: null 错误时不返回数据
     * - status(500): 设置HTTP状态码为500（服务器内部错误）
     */
    res.status(500).json({
      status: 1,
      msg: '获取国家列表失败',
      data: null
    });
  }
});

/**
 * ====================
 * 模块导出
 * ====================
 * 功能：导出路由实例供app.js使用
 * 在app.js中通过app.use('/api/app', require('./routes/app'))注册
 */
module.exports = router;